=begin pod

=TITLE class Map

=SUBTITLE Immutable mapping from strings to values

=for code :skip-test
class Map does Associative is Iterable { }

A Map is an immutable mapping from string keys to values of arbitrary
types. It serves as a base class for L<Hash>, which is mutable.

In list context a Map behaves as a list of L<Pair> objects.

Note that the order in which keys, values and pairs are retrieved is
generally arbitrary, but the C<keys>, C<values> and C<pairs> methods
return them always in the same order when called on the same object.

    my %e := Map.new('a', 1, 'b', 2);
    say %e.keys;    # can print "a b\n" or "b a\n";
    say %e.values;  # prints "1 2\n" if the previous line
                    # printed "a b\n", "b a\n" otherwise

=head1 Methods

=head2 method new

Defined as:

    method new(*@args)

Creates a new Map from a list of alternating keys and values, with
L<the same semantics|/type/Hash#Hash_assignment> as described for
hash assigning in the L<Hash> documentation, B<except>, for literal
pair handling. To ensure pairs correctly get passed, add extra
parentheses around all the arguments.

    my %h = Map.new('a', 1, 'b', 2);

    # WRONG: :b(2) interpreted as named argument
    say Map.new('a', 1, :b(2) ).keys; # OUTPUT: «(a)␤»

    # RIGHT: :b(2) interpreted as part of Map's contents
    say Map.new( ('a', 1, :b(2)) ).keys; # OUTPUT: «(a b)␤»

=head2 method elems

Defined as:

    method elems(Map:D: --> Int:D)

Returns the number of pairs stored in the Map.

    my %map = Map.new('a', 1, 'b', 2);
    say %map.elems; # OUTPUT: «2␤»

=head2 method ACCEPTS

Defined as:

    multi method ACCEPTS(Map:D: Positional $topic)
    multi method ACCEPTS(Map:D: Cool:D     $topic)
    multi method ACCEPTS(Map:D: Regex      $topic)
    multi method ACCEPTS(Map:D: Any        $topic)

Used in smart-matching if the right-hand side is an C<Map>.

If the topic is list-like (L<Positional>), returns True if
any of the list elements exist as a key in the Map.

If the topic is of type C<Cool> (strings, integers etc.),
returns True if the topic exists as a key.

If the topic is a regex, returns True if any of the keys match
the regex.

As a fallback, the topic is coerced to a list, and the C<Positional>
behavior is applied.

To retrieve a value from the Map by key, use the C<{ }> postcircumfix
operator:

    my $map = Map.new('a', 1, 'b', 2);
    say $map{'a'}; # OUTPUT: «1␤»

To check whether a given key is stored in a Map, modify the access
with the C<:exists> adverb:

    my $map = Map.new('a', 1, 'b', 2);
    my $key = 'a';
    if $map{$key}:exists {
        say "$map{} has key $key";
    }

=head2 method gist

Defined as:

    method gist(Map:D: --> Str:D)

Returns the string containing the "gist" of the L<Map>,
sorts the pairs and lists B<up to the first 100>,
appending an ellipsis if the L<Map> has more than 100 pairs.

=head2 method keys

Defined as:

    method keys(Map:D: --> Seq:D)

Returns a C<Seq> of all keys in the Map.

    my $m = Map.new('a' => (2, 3), 'b' => 17);
    say $m.keys; # OUTPUT: «(a b)␤»

=head2 method values

Defined as:

    method values(Map:D: --> Seq:D)

Returns a C<Seq> of all values in the Map.

    my $m = Map.new('a' => (2, 3), 'b' => 17);
    say $m.values; # OUTPUT: «((2 3) 17)␤»

=head2 method pairs

Defined as:

    method pairs(Map:D: --> Seq:D)

Returns a C<Seq> of all pairs in the Map.

    my $m = Map.new('a' => (2, 3), 'b' => 17);
    say $m.pairs; # OUTPUT: «(a => (2 3) b => 17)␤»

=head2 method antipairs

Defined as:

    method antipairs(Map:D: --> Seq:D)

Returns all keys and their respective values as a L<Seq|/type/Seq> of C<Pair>s
where the keys and values have been exchanged, i.e. the opposite of method
L<pairs|#method_pairs>. Unlike the L<invert|#method_invert> method, there is
no attempt to expand list values into multiple pairs.

    my $m = Map.new('a' => (2, 3), 'b' => 17);
    say $m.antipairs;                                  # OUTPUT: «((2 3) => a 17 => b)␤»

=head2 method invert

Defined as:

    method invert(Map:D: --> Seq:D)

Returns all keys and their respective values as a L<Seq|/type/Seq> of C<Pair>s
where the keys and values have been exchanged. The difference between C<invert>
and L<antipairs|#method_antipairs> is that C<invert> expands list values into
multiple pairs.

    my $m = Map.new('a' => (2, 3), 'b' => 17);
    say $m.invert;                                    # OUTPUT: «(2 => a 3 => a 17 => b)␤»

=head2 method kv

Defined as:

    method kv(Map:D: --> Seq:D)

Returns a C<Seq> of keys and values interleaved.

    Map.new('a', 1, 'b', 2).kv  # (a 1 b 2)

=head2 method Int

Defined as:

    method Int(Map:D: --> Int:D)

Returns the number of pairs stored in the C<Map> (same as C<.elems>).

    my $m = Map.new('a' => 2, 'b' => 17);
    say $m.Int;                                       # OUTPUT: «2␤»

=head2 method Numeric

Defined as:

    method Numeric(Map:D: --> Int:D)

Returns the number of pairs stored in the C<Map> (same as C<.elems>).

    my $m = Map.new('a' => 2, 'b' => 17);
    say $m.Numeric;                                   # OUTPUT: «2␤»

=head2 method Bool

Defined as:

    method Bool(Map:D: --> Bool:D)

Returns C<True> if the invocant contains at least one key/value pair.

    my $m = Map.new('a' => 2, 'b' => 17);
    say $m.Bool;                                      # OUTPUT: «True␤»

=head2 method Capture

Defined as:

    method Capture(Map:D: --> Capture:D)

Returns a L<Capture|/type/Capture> where each key, if any, has been converted
to a named argument with the same value as it had in the original C<Map>.
The returned C<Capture> will not contain any positional arguments.

    my $map = Map.new('a' => 2, 'b' => 17);
    my $capture = $map.Capture;
    my-sub(|$capture);                                # RESULT: «2, 17»

    sub my-sub(:$a, :$b) {
        say "$a, $b"
    }

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
